home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 24 / Amiga Format AFCD24 (Feb 1998, Issue 108).iso / -seriously_amiga- / shareware / programming / other / robodoc3.0j / robodoc.readme < prev    next >
Text File  |  1998-01-05  |  19KB  |  577 lines
  1. Short:    V3.0j, Autodocs HTML/GUIDE/RTF/LATEX
  2. Author:   slothoub@xs4all.nl
  3. Uploader: slothoub@xs4all.nl
  4. Type:     dev/misc
  5.  
  6.  
  7.  
  8.                          Robodoc v3.0j
  9.  
  10.        (c)  20 Dec 1997,  Maverick Software Development
  11.  
  12.  
  13.                  robodoc documentation for the;
  14.                          Amiga systems
  15.                        DEC Alpha systems
  16.                         DEC VAX systems
  17.                           UNIX systems
  18.                         Windows NT systems
  19.  
  20.           Original program and idea:  Jacco van Weert
  21.                      Versions 2.0 and up:
  22.  Frans Slothouber, Bernd Koesling, Anthon Pang, and Thomas Aglassinger
  23.  
  24.  
  25.      New versions of Robodoc are made available on AmiNet.
  26.  
  27.  
  28.  
  29.                           1.0  Preface
  30.                           ------------
  31.  
  32. The complete Robodoc archive is copyrighted by Jacco van Weert, and
  33. Frans Slothouber of Maverick Software Development.
  34.  
  35. Robodoc can be freely distributed on FREEWARE base as long as all
  36. files remains in their original state, no files may be added to the
  37. archive, and also no files may be excluded.
  38.  
  39. This software is provided on an "AS IS" basis without warranty of any
  40. kind.  We are not responsible for any damage to your hardware,
  41. software, or brain, caused by using this software.
  42.  
  43. You can use Robodoc with C, Assembler, Basic, Fortran, LaTex, and PS
  44. programs.  Additional languages can be used by a few modifications to
  45. the source code.
  46.  
  47.  
  48.  
  49.                         2.0 Introduction
  50.                         ----------------
  51.  
  52. Robodoc is based on the AutoDocs program written some time ago by
  53. Commodore.  The idea is to include for every function a standard
  54. header containing all sorts of information about that
  55. procedure/function.  An AutoDocs program will extract those headers
  56. from the source file and put them in a autodocs-file.  This way you
  57. can include the program documentation in the source code and is it not
  58. necessary to maintain two documents.
  59.  
  60. Robodoc is such a program, however Robodoc has several additions.  For
  61. one it can generate the documentation in different formats, ASCII,
  62. HTML, RTF, LaTex, and AmigaGuide.  Another feature is that it can
  63. fully automatically create links within the document, and to other
  64. documents.  It is also possible to include parts of the source in you
  65. document, complete with links.  For instance it is possible to include
  66. a complete subroutine, and have the function names in this subroutine
  67. point to their documentation.
  68.  
  69. If you never have used AutoDoc or Robodoc before you might take a look
  70. at the example in the examples directory.  These are two amigaguide
  71. files that contain the documentation generated with Robodoc of the
  72. Robodoc program itself.
  73.  
  74. Robodoc can generate the documentation in five different
  75. formats:
  76.   o ASCII format;
  77.     The autodocs-file is just a plain ASCII text-file, this file
  78.     is very closely related to the one that the original
  79.     AutoDocs program would generated.
  80.   o AmigaGuide format;
  81.     This is a format used on the Amiga computers to view in a
  82.     HyperText way a text-file.  The AmigaGuide program is
  83.     necessary to view the resulting autodocs-file.
  84.   o HTML format;
  85.     The autodocs-file will be written as a HTML-file (HyperText
  86.     Markup Language), this format is used on the WWW-Internet.
  87.     By using a Mosaic/Netscape program you view the
  88.     documentation.
  89.   o LaTex
  90.   o RTF
  91.  
  92.  
  93.  
  94.             3.0  Hardware and software requirements
  95.             ---------------------------------------
  96.  
  97. Robodoc was developed on a standard Amiga 1200.  It is written in C,
  98. and has been successfully compiled with SAS/C 6.50 and DICE C.
  99. However it is written according to the ansi C standard and uses no
  100. special functions, so it should run on every system with a C-compiler.
  101. For instance it also has been successfully compiled with gcc on a Sun
  102. system.
  103.  
  104. The complete source code consists of two files; Robodoc.c and
  105. Robodoc.h.
  106.  
  107.  
  108.                   4.0 This Version Of Robodoc
  109.                   ---------------------------
  110.  
  111. This is version 3.0j of Robodoc, containing a number of bug fixes, and
  112. conforms to the DTD for HTML-3.2 (thanks to the work of Thomas
  113. Aglassinger).
  114.  
  115.  
  116.    5.0  How to format your code so that you can use Robodoc.
  117.    ---------------------------------------------------------
  118.  
  119. Robodoc allows you to mix the program documentation with the
  120. source code.  It does require though that this documentation has
  121. a particular layout so Robodoc can recognize it.
  122.  
  123. The following header was taken from the original Robodoc
  124. program.
  125.  
  126.   /****h* AUTODOC/robodoc [2.0d]
  127.   *
  128.   *  NAME
  129.   *    robodoc -- AutoDoc formatter
  130.   *  COPYRIGHT
  131.   *    Maverick Software Development
  132.   *  FUNCTION
  133.   *    Robodoc is indented as a replacement for the original
  134.   *    AutoDocs program Robodoc will extract from a source file
  135.   *    the procedure comment headers and put them in a separate
  136.   *    documentation file.
  137.   *  CREATION DATE
  138.   *    20-Dec-94
  139.   *  MODIFICATION HISTORY
  140.   *    25-Jan-94     -       v0.92: First version
  141.   *    10-Mar-95     -       v1.0 : Complete version
  142.   *    10-May-1995   -       v2.0 : Major update.
  143.   *  NOTES
  144.   *    Has been successfully compiled with DICE and SAS.
  145.   *******
  146.   */
  147.  
  148. It includes two special markers, and a number of items.  There is
  149. a marker that marks the beginning of a header and one that marks
  150. the end of a header.
  151.  
  152. This header is intended for a program in C, a same header for
  153. another languages would look a slightly different.  However
  154. Robodoc recognizes some other types markers to:
  155.  
  156. /****                        C
  157. ;****                        Assembler
  158. ****                         Assembler
  159. REM ****                     Basic
  160. C     ****                   Fortran
  161. %****                        LaTeX, TeX, Postscript
  162.  
  163.  
  164. After which a "i", "*" or "h" (header type) should follow, then
  165. another * and then:
  166.  
  167. <MOD>/<PROC><SP>[<VERSION>]<SP><REST>
  168.  
  169. Where:
  170. <SP>      - is any sequence of white characters (spaces of tabs),
  171.             excluding the empty string.
  172. <TYPE>    - The header type, this is one of the following characters,
  173.             'h' = MainProgram, '*' = Normal header, 'i' = Internal
  174.             header.
  175. <MOD>     - Module name, any sequence of non white characters, except
  176.             '/'.
  177. <FUNC>    - Function name, any sequence of non white characters.
  178. <VERSION> - A version number, any sequence of non white characters,
  179.             except ']'.
  180. <REST>    - rest of the line, any sequence of characters.
  181.  
  182.  
  183. This might look terribly complicated but here are some examples:
  184.  
  185. In C
  186.    /****h* programs/greatprogram.library [1.0] *
  187.  
  188. In Assembler
  189.    ****** greatprogram.library/program_init
  190.    ;****i* greatprogram.library/very_secret [2.0d] ***
  191.  
  192. In Fortran
  193.    C     ****h* programs/greatprogram.library         C
  194.  
  195. In Basic, (assuming you don't use basis that still needs line numbers).
  196.    REM ****h* programs/greatprogram.library
  197.  
  198.  
  199. A header ends with at least three asterisks at the start of a
  200. line ("***") right after the remark marker.  In general Robodoc
  201. will recognize anything of the that starts with:
  202.  
  203. C    ***
  204. REM ***
  205. ***/
  206. ;***
  207. %***
  208.  
  209.  
  210.  
  211.  
  212.                         5.1 Header Types
  213.                         ----------------
  214.  
  215. Robodoc handles three different type of headers;
  216.   o MainProgram header (optional);
  217.     These headers are placed at the start of a program and
  218.     containing some general information about the program.
  219.     These where not available in the original AutoDocs program.
  220.   o Normal header;
  221.     The normal header, available to the general public.
  222.   o Internal header;
  223.     The internal header not available to the general public,
  224.     mainly used by the programmer him/herself.
  225.  
  226.  
  227.                        5.2 Header Items.
  228.                        -----------------
  229.  
  230. When Robodoc has found a header it will try to identify items,
  231. currently it looks for one of the following item names:
  232.  
  233.   "NAME", "COPYRIGHT", "SYNOPSIS",
  234.   "FUNCTION", "DESCRIPTION", "AUTHOR",
  235.   "CREATION DATE", "MODIFICATION HISTORY", "HISTORY",
  236.   "INPUTS", "ARGUMENTS", "OPTIONS", "PARAMETERS", "SWITCHES",
  237.   "OUTPUT", "SIDE EFFECTS", "RESULT", "RETURN VALUE",
  238.   "EXAMPLE", "NOTES", "DIAGNOSTICS",
  239.   "WARNINGS", "ERRORS", "BUGS", "TODO", "IDEAS",
  240.   "PORTABILITY", "SEE ALSO", "SOURCE",
  241.   "BEAST METHODS", "NEW METHODS",
  242.   "BEAST ATTRIBUTES", "NEW ATTRIBUTES",
  243.  
  244. Robodoc does this so that it can format each item with a
  245. different style (colour, font, etc.) if the user want it.  These
  246. can be specified in the Robodoc.defaults file, see the next
  247. section more information.
  248.  
  249. To get an idea what the various items are meant for take a look
  250. at the following header that was taken from the original AutoDoc
  251. documentation (hope they don't object to this;)
  252.  
  253.   /****** financial.library/StealMoney *****************************
  254.   *
  255.   *  NAME
  256.   *    StealMoney -- Steal money from the Federal Reserve Bank. (V77)
  257.   *  SYNOPSIS
  258.   *    error = StealMoney( userName,amount,destAccount,falseTrail )
  259.   *    D0,Z                D0       D1.W    A0         [A1]
  260.   *
  261.   *    BYTE StealMoney
  262.   *         ( STRPTR,UWORD,struct AccountSpec *,struct falseTrail *);
  263.   *  FUNCTION
  264.   *    Transfer money from the Federal Reserve Bank into the
  265.   *    specified interest-earning checking account.  No records of
  266.   *    the transaction will be retained.
  267.   *  INPUTS
  268.   *    userName    - name to make the transaction under.  Popular
  269.   *                  favorites include "Ronald Reagan" and
  270.   *                  "Mohamar Quadaffi".
  271.   *    amount      - Number of dollars to transfer (in thousands).
  272.   *    destAccount - A filled-in AccountSpec structure detailing the
  273.   *                  destination account (see financial/accounts.h).
  274.   *                  If NULL, a second Great Depression will be
  275.   *                  triggered.
  276.   *    falseTrail  - If the DA_FALSETRAIL bit is set in the
  277.   *                  destAccount, a falseTrail structure must be
  278.   *                  provided.
  279.   *  RESULT
  280.   *    error - zero for success, else an error code is returned
  281.   *           (see financial/errors.h).  The Z condition code
  282.   *           is guaranteed.
  283.   *  EXAMPLE
  284.   *    Federal regulations prohibit a demonstration of this function.
  285.   *  NOTES
  286.   *    Do not run on Tuesdays!
  287.   *  BUGS
  288.   *    Before V88, this function would occasionally print the
  289.   *    address and home phone number of the caller on local police
  290.   *    976 terminals.  We are confident that this problem has been
  291.   *    resolved.
  292.   *  SEE ALSO
  293.   *      CreateAccountSpec(),security.device/SCMD_DESTROY_EVIDENCE,
  294.   *      financial/misc.h
  295.   *
  296.   *******************************************************************/
  297.  
  298.  
  299.  
  300.                      5.2.1 The Source Item
  301.                     -----------------------
  302.  
  303. New for version 2.0 is the source item. It allows you to include
  304. part of the source in the documentation as is demonstrated by the
  305. following example.
  306.  
  307.   /****i* Robodoc.c/RB_Panic [2.0d]
  308.   * NAME
  309.   *   RB_Panic -- Shout panic, free resources, and shut down.
  310.   * SYNOPSIS
  311.   *   RB_Panic (cause, add_info)
  312.   *   RB_Panic (char *, char *)
  313.   * FUNCTION
  314.   *   Prints an error message.
  315.   *   Frees all resources used by robodoc.
  316.   *   Terminates program.
  317.   * INPUTS
  318.   *   cause    - pointer to a string with the describes the
  319.   *              cause of the error.
  320.   *   add_info - pointer to a string with additional information.
  321.   * SEE ALSO
  322.   *   RB_Close_The_Shop ()
  323.   * SOURCE
  324.   */
  325.  
  326.   void RB_Panic (char *cause, char *add_info)
  327.   {
  328.     printf ("Robodoc: Error, %s\n",cause) ;
  329.     printf ("         %s\n", add_info) ;
  330.     printf ("Robodoc: Panic Fatal error, closing down...\n") ;
  331.     RB_Close_The_Shop () ;
  332.     exit(100) ;
  333.   }
  334.  
  335.   /*******/
  336.  
  337. The source item is in an experimental stage at the moment.  All
  338. lines between the source item and the following item are copied
  339. verbatim to the AutoDocs document.  It might be possible that
  340. certain expressions within the source conflict with the
  341. amigaguide program or a HTML viewer.  If so please report them
  342. to me, that is <slothoub@xs4all.nl>, so they can perhaps be
  343. solved in a next release a Robodoc.
  344.  
  345.  
  346. 5.3 The Robodoc Defaults file.
  347.  
  348. The robodoc.default file can be used to change the appearance of
  349. the documentation. For each item type you can define how the
  350. corresponding text should be rendered.
  351.  
  352. Each line in the default file consists of two parts, the item type
  353. and the item attributes. For instance
  354.  
  355. AUTHOR                    LARGE ITALICS BOLD UNDERLINE
  356.  
  357. Specifies that the AUTHOR item has the attributes LARGE,
  358. ITALICS, BOLD, and UNDERLINE.
  359.  
  360. The effect of each attribute is listed in the following table.
  361.  
  362. Item Attributes        GUIDE                     HTML
  363. --------------------------------------------------------------
  364. LARGE                  @{b},@{ub}      <FONT SIZE=5>,</FONT>
  365. SMALL                                  FONT SIZE=-1>,</FONT>
  366. NONPROP                                       </PRE>,<PRE>
  367. ITALICS                @{i},@{ui}                <I>,</I>
  368. BOLD                   @{b},@{ub}                <B>,</B>
  369. UNDERLINE              @{u},@{uu}                <U>,</U>
  370. SHINE           @{fg shine},@{fg text}          <EM>,</EM>
  371. HIGHLIGHT   @{fg highlight},@{fg text}          <EM>,</EM>
  372.  
  373.  
  374.  
  375.  
  376.             5.4 Creating links within the document.
  377.             ---------------------------------------
  378.  
  379. Creating links within the document is the most interesting
  380. feature of Robodoc.  A document with such links is much more
  381. easier to read.
  382.  
  383. If your source code consists of just one file, creating links is
  384. easy.  Just tell Robodoc that you want to have the output in
  385. HTML or AmigaGuide format, and it will automatically generate
  386. the links.  That is, at the beginning of the document it will
  387. create a table of contents that consists of links to all your
  388. function headers.
  389.   Robodoc will also search the complete text of you
  390. documentation for reference to function names, and it will
  391. create a link to the documentation of that function.
  392.  
  393. An example, assume you have the following function header in your
  394. source:
  395.  
  396. /****** Airmail.c/ZM_xpr_fopen [2.0a]
  397. * NAME
  398. *   ZM_xpr_fopen -- open a file.
  399. * SYNOPSIS
  400. *   filehandle = ZM_xpr_fopen (filename, accessmode)
  401. *           long ZM_xpr_fopen (char *, char *)
  402. * FUNCTION
  403. *   Open a file.
  404. * INPUTS
  405. *   filename    - pointer to a string containing the file name.
  406. *   accessmode  - how the file should be opened (C compatible).
  407. * RESULT
  408. *   a pointer to the opened file.
  409. *   0 -- if the open failed
  410. * SEE ALSO
  411. *   ZM_xpr_fread, ZM_xpr_fwrite, ZM_xpr_fclose.
  412. ******
  413. */
  414.  
  415. It will automatically turn "ZM_xpr_fread", "ZM_xpr_fwrite", and
  416. "ZM_xpr_fclose" into links to the documentation of these
  417. functions, (provided you have documented them of course).
  418.  
  419.  
  420.  
  421.                        6.0 The XREF files
  422.                        ------------------
  423.  
  424. The previous section described how to create links within a
  425. document, it is also possible, however, to create links to other
  426. files.  This does require the use of some additional files,
  427. called xref files, but these can also be generated with Robodoc.
  428. These xref files contain information about were certain
  429. references can be found and in which file.
  430.  
  431. Lets assume your project is split up in five different source
  432. files, and you want to generate links between these five files.
  433. What you have to do to accomplish this is to create a xref file
  434. for each of those five files.
  435.  
  436. With the GENXREF option Robodoc will generate such a xref file
  437. from the a source-file.  When you use this option, ONLY the xref
  438. file is created NOT the autodocs-file, however you still have to
  439. specify the name of the autodocs file because this name is
  440. needed for the creation of the xref file.
  441.  
  442. When all the xref files are created the documentation can be
  443. created.  To do so you have to use the XREF option and
  444. parameter.  This parameter contains the name of the file in
  445. which the names all xref files are defined (xreflist_filename).
  446. Notice:  this is a file with FILE NAMES, and you must created it
  447. by hand.
  448.  
  449. Xref files can also be created by the user or by other means,
  450. e.g.  the Autodoc.xref.  robodoc uses the same format as these
  451. standard XREF files.
  452.  
  453. An Example will make thing more clearly:
  454.  
  455. In the robodoc.lha archive there are two example programs
  456. prog1.C and prog2.C.
  457.  
  458. First create the xref files when want to create amigaguide
  459. autodocs-files:
  460.  
  461. Robodoc prog1.c prog1.guide GENXREF prog1.c.xref GUIDE
  462. Robodoc prog2.c prog2.guide GENXREF prog2.c.xref GUIDE
  463.  
  464. Now there are two xref files:  prog1.xref and prog2.xref.
  465.  
  466. Now create a <xreflist_filename> file.
  467. This file will hold only two lines;
  468. prog1.c.xref
  469. prog2.c.xref
  470.  
  471. More xref files can be added.  The name of this file can be
  472. anything, say it is "xref_files".
  473.  
  474. Now generate the final documentation;
  475.  
  476. robodoc prog1.c prog1.c.guide XREF xref_files GUIDE
  477. Robodoc prog2.c prog2.c.guide XREF xref_files GUIDE
  478.  
  479.  
  480.  
  481.  
  482.                       7.0 Usage of Robodoc
  483.                       --------------------
  484.  
  485. When you call Robodoc you should at least provide two parameters
  486.  
  487. Robodoc <sourcefile> <autodocfile>
  488.  
  489. Here <sourcefile> is the file with the program source of which
  490. you want to extract the documentation from and <autodocfile> is
  491. the file were you want the documentation to be stored.
  492.  
  493. In addition to this you can specify one of the following
  494. options:
  495.  
  496. ASCII
  497.  
  498.   The documentation will be in ASCII format (default).
  499.  
  500. GUIDE
  501.  
  502.   The documentation will be in AmigaGuide format.
  503.  
  504. HTML
  505.  
  506.   The documentation will be in HTML format.
  507.  
  508. LATEX
  509.  
  510.   The documentation will be in LATEX format.  (Experimental)
  511.  
  512. RTF
  513.  
  514.   The documentation will be in RTF format.
  515.  
  516. GENXREF <xref_filename>
  517.  
  518.   Generate a xref file, which then can be used to created
  519.   references within the documentation.
  520.  
  521. XREF <xreflist_filename>
  522.  
  523.   Use a set of xref files to create references (links) to other
  524.   documents or within the document.
  525.  
  526. INTERNAL
  527.  
  528.   Also include headers that are marked internal.
  529.  
  530. INTERNALONLY
  531.  
  532.   Only extract the headers marked internal.
  533.  
  534. SORT
  535.  
  536.   Sort the headers alphabetically.
  537.  
  538. TOC
  539.  
  540.   Generate a table of contents.  Is only useful when you select
  541.   ASCII as output mode.  With all other output modes the Table of
  542.   contents is generated anyway.
  543.  
  544. TABSIZE <number>
  545.  
  546.   Convert each tab into <number> spaces.
  547.  
  548. -v
  549.  
  550.   Verbose option, Robodoc will tell you what it is doing.
  551.  
  552.  
  553. The following abbreviations are also allowed:
  554.  
  555.   SORT         = -s
  556.   TOC          = -t
  557.   XREF         = -x
  558.   GENXREF      = -g
  559.   INTERNAL     = -i
  560.   INTERNALONLY = -io
  561.   TABSIZE      = -ts
  562.  
  563.  
  564.  
  565.  
  566.                     8.0 Suggestions or bugs
  567.                     -----------------------
  568.  
  569. If you find any bugs, catch them, put them in a jar, and send
  570. them to:
  571.  
  572.    slothoub@xs4all.nl.
  573.  
  574. Suggestions are also welcome on this address.
  575.  
  576. Flames can be directed to the sun....
  577.